/*
 * Copyright 2012-2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.context.config;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.EnumSet;
import java.util.List;
import java.util.Set;
import java.util.function.Consumer;

import org.springframework.core.env.Environment;
import org.springframework.core.env.PropertySource;
import org.springframework.util.Assert;

/**
 * 从 {@link ConfigDataResource} 中加载的配置数据，最终可能会为 Spring 的
 * {@link Environment} 贡献 {@link PropertySource 属性源}。
 *
 * @author Phillip Webb
 * @author Madhura Bhave
 * @since 2.4.0
 * @see ConfigDataLocationResolver
 * @see ConfigDataLoader
 */
public final class ConfigData {

	private final List<PropertySource<?>> propertySources;

	private final PropertySourceOptions propertySourceOptions;

	/**
	 * 一个 {@link ConfigData} 实例，不包含任何配置数据。
	 */
	public static final ConfigData EMPTY = new ConfigData(Collections.emptySet());

	/**
	 * 创建一个新的 {@link ConfigData} 实例，该实例对每个属性源应用相同的配置选项。
	 *
	 * @param propertySources 配置数据属性源，按优先级升序排列
	 * @param options 应用于每个属性源的配置数据选项
	 * @see #ConfigData(Collection, PropertySourceOptions)
	 */
	public ConfigData(Collection<? extends PropertySource<?>> propertySources, Option... options) {
		this(propertySources, PropertySourceOptions.always(Options.of(options)));
	}

	/**
	 * 使用指定的属性源选项创建一个新的 {@link ConfigData} 实例。
	 *
	 * @param propertySources 配置数据属性源，按优先级升序排列
	 * @param propertySourceOptions 属性源选项策略
	 * @since 2.4.5
	 */
	public ConfigData(Collection<? extends PropertySource<?>> propertySources,
			PropertySourceOptions propertySourceOptions) {
		Assert.notNull(propertySources, "PropertySources must not be null");
		Assert.notNull(propertySourceOptions, "PropertySourceOptions must not be null");
		this.propertySources = Collections.unmodifiableList(new ArrayList<>(propertySources));
		this.propertySourceOptions = propertySourceOptions;
	}

	/**
	 * 以优先级升序返回配置数据属性源列表。如果多个源中包含相同的键，
	 * 则后面的源中的值会覆盖前面的源中的值。
	 *
	 * @return 配置数据属性源列表
	 */
	public List<PropertySource<?>> getPropertySources() {
		return this.propertySources;
	}

	/**
	 * 返回此源的一个 {@link Option 配置数据选项} 集合。
	 *
	 * @return 配置数据选项集合
	 * @deprecated 自 2.4.5 起弃用，请使用 {@link #getOptions(PropertySource)} 方法替代
	 */
	@Deprecated
	public Set<Option> getOptions() {
		Assert.state(this.propertySourceOptions instanceof AlwaysPropertySourceOptions, "No global options defined");
		return this.propertySourceOptions.get(null).asSet();
	}

	/**
	 * 返回适用于给定源的 {@link Options 配置数据选项}。
	 *
	 * @param propertySource 要检查的属性源
	 * @return 适用的选项
	 * @since 2.4.5
	 */
	public Options getOptions(PropertySource<?> propertySource) {
		Options options = this.propertySourceOptions.get(propertySource);
		return (options != null) ? options : Options.NONE;
	}

	/**
	 * 策略接口，用于为给定的 {@link PropertySource} 提供对应的 {@link Options}。
	 *
	 * @since 2.4.5
	 */
	@FunctionalInterface
	public interface PropertySourceOptions {

		/**
		 * 一个 {@link PropertySourceOptions} 实例，始终返回
		 * {@link Options#NONE}，即不启用任何选项。
		 *
		 * @since 2.4.6
		 */
		PropertySourceOptions ALWAYS_NONE = new AlwaysPropertySourceOptions(Options.NONE);

		/**
		 * 返回适用于给定属性源的选项配置。
		 *
		 * @param propertySource 给定的属性源
		 * @return 应用于此属性源的选项
		 */
		Options get(PropertySource<?> propertySource);

		/**
		 * 创建一个新的 {@link PropertySourceOptions} 实例，
		 * 该实例无论面对哪个属性源，都会始终返回相同的选项。
		 *
		 * @param options 要返回的固定选项
		 * @return 新的 {@link PropertySourceOptions} 实例
		 */
		static PropertySourceOptions always(Option... options) {
			return always(Options.of(options));
		}

		/**
		 * 创建一个新的 {@link PropertySourceOptions} 实例，
		 * 该实例无论面对哪个属性源，都会始终返回相同的选项。
		 *
		 * @param options 要返回的固定选项
		 * @return 新的 {@link PropertySourceOptions} 实例
		 */
		static PropertySourceOptions always(Options options) {
			if (options == Options.NONE) {
				return ALWAYS_NONE;
			}
			return new AlwaysPropertySourceOptions(options);
		}

	}

	/**
	 * 一个 {@link PropertySourceOptions} 实现，始终返回相同的结果。
	 */
	private static class AlwaysPropertySourceOptions implements PropertySourceOptions {

		private final Options options;

		AlwaysPropertySourceOptions(Options options) {
			this.options = options;
		}

		@Override
		public Options get(PropertySource<?> propertySource) {
			return this.options;
		}

	}

	/**
	 * 一组 {@link Option} 选项标志。
	 *
	 * @since 2.4.5
	 */
	public static final class Options {

		/**
		 * 没有任何选项的状态。
		 */
		public static final Options NONE = new Options(Collections.emptySet());

		private final Set<Option> options;

		private Options(Set<Option> options) {
			this.options = Collections.unmodifiableSet(options);
		}

		Set<Option> asSet() {
			return this.options;
		}

		/**
		 * 判断指定的选项是否包含在该选项集合中。
		 *
		 * @param option 要检查的选项
		 * @return 如果集合中包含该选项，则返回 {@code true}
		 */
		public boolean contains(Option option) {
			return this.options.contains(option);
		}

		@Override
		public boolean equals(Object obj) {
			if (this == obj) {
				return true;
			}
			if (obj == null || getClass() != obj.getClass()) {
				return false;
			}
			Options other = (Options) obj;
			return this.options.equals(other.options);
		}

		@Override
		public int hashCode() {
			return this.options.hashCode();
		}

		@Override
		public String toString() {
			return this.options.toString();
		}

		/**
		 * 创建一个新的{@link Options}实例，该实例包含当前集合中的选项但排除给定选项。
		 * @param option 要排除的选项
		 * @return 一个新的{@link Options}实例
		 */
		public Options without(Option option) {
			return copy((options) -> options.remove(option));
		}

		/**
		 * 创建一个新的{@link Options}实例，该实例包含当前集合中的选项并添加给定选项。
		 * @param option 要包含的选项
		 * @return 一个新的{@link Options}实例
		 */
		public Options with(Option option) {
			return copy((options) -> options.add(option));
		}

		private Options copy(Consumer<EnumSet<Option>> processor) {
			EnumSet<Option> options = EnumSet.noneOf(Option.class);
			options.addAll(this.options);
			processor.accept(options);
			return new Options(options);
		}

		/**
		 * 使用给定的{@link Option}值创建一个新实例。
		 * @param options 要包含的选项
		 * @return 一个新的{@link Options}实例
		 */
		public static Options of(Option... options) {
			Assert.notNull(options, "Options must not be null");
			if (options.length == 0) {
				return NONE;
			}
			return new Options(EnumSet.copyOf(Arrays.asList(options)));
		}

	}

	/**
	 * 可应用的选项标志。
	 */
	public enum Option {

		/**
		 * 忽略来源中的所有导入属性。
		 */
		IGNORE_IMPORTS,

		/**
		 * 忽略所有配置文件激活和包含属性。
		 * @since 2.4.3
		 */
		IGNORE_PROFILES,

		/**
		 * 表示该来源是"特定于配置文件的"，且应被包含在特定于配置文件的同级导入之后。
		 * @since 2.4.5
		 */
		PROFILE_SPECIFIC;

	}

}
